
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>Introduction to LAVA &#8212; LAVA 2024.05 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Contents" href="contents.html" />
    <link rel="canonical" href="https://docs.lavasoftware.org/lava/index.html" />
  
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>


  </head><body>

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="#"><span><img src="_static/lava.png"></span>
          LAVA</a>
        <span class="navbar-text navbar-version pull-left"><b>2024.05</b></span>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            
                <li><a href="genindex.html">Index</a></li>
                <li><a href="contents.html">Contents</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Site <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Introduction to LAVA</a></li>
<li class="toctree-l1"><a class="reference internal" href="contents.html">Contents</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary of terms</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="support.html">Getting support</a></li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Introduction to LAVA</a><ul>
<li><a class="reference internal" href="#navigation">Navigation</a><ul>
<li><a class="reference internal" href="#id1">Index</a></li>
<li><a class="reference internal" href="#id2">Contents</a></li>
<li><a class="reference internal" href="#page-indices">Page indices</a></li>
</ul>
</li>
<li><a class="reference internal" href="#about-lava-v2">About LAVA V2</a></li>
</ul>
</li>
<li><a class="reference internal" href="#lava-overview">LAVA Overview</a><ul>
<li><a class="reference internal" href="#what-is-lava">What is LAVA?</a></li>
<li><a class="reference internal" href="#what-is-lava-not">What is LAVA <strong>not</strong>?</a></li>
<li><a class="reference internal" href="#features">Features</a></li>
<li><a class="reference internal" href="#architecture">Architecture</a><ul>
<li><a class="reference internal" href="#elements-of-the-master">Elements of the Master</a></li>
<li><a class="reference internal" href="#elements-of-the-worker">Elements of the Worker</a></li>
</ul>
</li>
<li><a class="reference internal" href="#preparation">Preparation</a></li>
<li><a class="reference internal" href="#methods">Methods</a><ul>
<li><a class="reference internal" href="#deployment-methods">Deployment methods</a></li>
<li><a class="reference internal" href="#boot-methods">Boot methods</a></li>
<li><a class="reference internal" href="#test-methods">Test methods</a></li>
<li><a class="reference internal" href="#multiple-device-testing">Multiple device testing</a></li>
<li><a class="reference internal" href="#scheduling">Scheduling</a></li>
<li><a class="reference internal" href="#advanced-use-cases">Advanced use cases</a></li>
</ul>
</li>
<li><a class="reference internal" href="#glossary">Glossary</a></li>
<li><a class="reference internal" href="#support">Support</a></li>
<li><a class="reference internal" href="#full-documentation">Full documentation</a></li>
</ul>
</li>
</ul>
</ul>
</li>
              
            
            
              
                
  <li>
    <a href="contents.html" title="Next Chapter: Contents"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Contents &raquo;</span>
    </a>
  </li>
              
            
            
            
            
              <li class="hidden-sm"></li>
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
    <div class="body col-md-12 content" role="main">
      
  <section id="introduction-to-lava">
<span id="toc"></span><span id="index-0"></span><h1>Introduction to LAVA<a class="headerlink" href="#introduction-to-lava" title="Permalink to this heading">¶</a></h1>
<section id="navigation">
<h2>Navigation<a class="headerlink" href="#navigation" title="Permalink to this heading">¶</a></h2>
<p>Use the navigation bar at the top of each page to quickly navigate
between sections of the documentation; <a class="reference external" href="genindex.html">Index</a>,
<a class="reference external" href="contents.html">Contents</a>, <a class="reference internal" href="#page-indices"><span class="std std-ref">Page</span></a> and <a class="reference external" href="contents.html">Next</a>.</p>
<section id="id1">
<h3>Index<a class="headerlink" href="#id1" title="Permalink to this heading">¶</a></h3>
<p>The <a class="reference external" href="genindex.html">Help Index</a> is often the quickest way to find
specific sections of the documentation.</p>
</section>
<section id="id2">
<h3>Contents<a class="headerlink" href="#id2" title="Permalink to this heading">¶</a></h3>
<p>If you are new to LAVA, the <a class="reference external" href="contents.html">Help Contents</a> describes
several useful starting points, depending on how you expect to use LAVA.</p>
</section>
<section id="page-indices">
<span id="id3"></span><h3>Page indices<a class="headerlink" href="#page-indices" title="Permalink to this heading">¶</a></h3>
<p>Each page also has a <strong>Page</strong> menu for topics within the page as well as
forward and back navigation to lead readers through in a logical manner.</p>
<figure class="fig-float align-center">
<a class="reference internal image-reference" href="_images/lava.svg"><img alt="LAVA logo" src="_images/lava.svg" width="50%" /></a>
</figure>
</section>
</section>
<section id="about-lava-v2">
<h2>About LAVA V2<a class="headerlink" href="#about-lava-v2" title="Permalink to this heading">¶</a></h2>
<p>LAVA V2 is the second major version of LAVA. The major user-visible features
are:</p>
<ul class="simple">
<li><p>The Pipeline model for the dispatcher</p></li>
<li><p>YAML job submissions</p></li>
<li><p>Results</p></li>
<li><p>Queries</p></li>
<li><p>Charts</p></li>
<li><p>Data export APIs</p></li>
</ul>
<p>The architecture has been significantly improved since V1, bringing major
changes in terms of how a distributed LAVA instance is installed, configured
and used for running test jobs.</p>
</section>
</section>
<section id="lava-overview">
<span id="id4"></span><h1>LAVA Overview<a class="headerlink" href="#lava-overview" title="Permalink to this heading">¶</a></h1>
<section id="what-is-lava">
<h2>What is LAVA?<a class="headerlink" href="#what-is-lava" title="Permalink to this heading">¶</a></h2>
<ul class="simple">
<li><p>LAVA is the Linaro Automation and Validation Architecture.</p></li>
<li><p>LAVA is a <a class="reference internal" href="lava_ci.html#continuous-integration"><span class="std std-ref">continuous integration</span></a> system for
deploying operating systems onto physical and virtual hardware for running
tests. Tests can be simple boot testing, bootloader testing and system level
testing, although extra hardware may be required for some system tests.
Results are tracked over time and data can be exported for further analysis.</p></li>
<li><p>LAVA is a collection of participating components in an evolving architecture.
LAVA aims to make systematic, automatic and manual quality control more
approachable for projects of all sizes.</p></li>
<li><p>LAVA is designed for validation during development - testing whether the code
that engineers are producing “works”, in whatever sense that means. Depending
on context, this could be many things, for example:</p>
<ul>
<li><p>testing whether changes in the Linux kernel compile and boot</p></li>
<li><p>testing whether the code produced by gcc is smaller or faster</p></li>
<li><p>testing whether a kernel scheduler change reduces power consumption for a
certain workload</p></li>
<li><p>etc.</p></li>
</ul>
</li>
<li><p>LAVA is good for automated validation. LAVA tests the Linux kernel on a range
of supported boards every day. LAVA tests proposed android changes in gerrit
before they are landed, and does the same for other projects like gcc. Linaro
runs a central validation lab in Cambridge, containing racks full of
computers supplied by Linaro members and the necessary infrastructure to
control them (servers, serial console servers, network switches etc.)</p></li>
<li><p>LAVA is good for providing developers with the ability to run customized test
on a variety of different types of hardware, some of which may be difficult
to obtain or integrate. Although LAVA has support for emulation (based on
QEMU), LAVA is best at providing test support for real hardware devices.</p></li>
<li><p>LAVA is principally aimed at testing changes made by developers across
multiple hardware platforms to aid portability and encourage multi-platform
development. Systems which are already platform independent or which have
been optimized for production may not necessarily be able to be tested in
LAVA or may provide no overall gain.</p></li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This overview document explains LAVA using
<a class="reference external" href="http://validation.linaro.org/">http://validation.linaro.org/</a> which is the official production instance of
LAVA hosted by Linaro. Where examples reference <code class="docutils literal notranslate"><span class="pre">validation.linaro.org</span></code>,
replace with the fully qualified domain name of your LAVA instance.</p>
</div>
</section>
<section id="what-is-lava-not">
<span id="id5"></span><h2>What is LAVA <strong>not</strong>?<a class="headerlink" href="#what-is-lava-not" title="Permalink to this heading">¶</a></h2>
<ul class="simple">
<li><p>LAVA is <strong>not</strong> a set of tests - it is infrastructure to enable
users to run their own tests. LAVA concentrates on providing a range of
deployment methods and a range of boot methods. Once the login is complete,
the test consists of whatever scripts the test writer chooses to execute in
that environment.</p></li>
<li><p>LAVA is <strong>not</strong> a test lab - it is the software that can used in a test lab
to control test devices.</p></li>
<li><p>LAVA is <strong>not</strong> a complete <abbr title="continuous integration">CI</abbr> system -  it
is software that can form part of a CI loop. LAVA supports data extraction to
make it easier to produce a frontend which is directly relevant to particular
groups of developers.</p></li>
<li><p>LAVA is <strong>not</strong> a build farm - other tools need to be used to prepare
binaries which can be passed to the device using LAVA.</p></li>
<li><p>LAVA is <strong>not</strong> a production test environment for hardware - LAVA is focused
on developers and may require changes to the device or the software to enable
automation. These changes are often unsuitable for production units. LAVA
also expects that most devices will remain available for repeated testing
rather than testing the software with a changing set of hardware.</p></li>
</ul>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="lava_ci.html#continuous-integration"><span class="std std-ref">Continuous Integration</span></a> which covers how LAVA relates to
continuous integration (CI) and covers the consequences of what LAVA can and
cannot do with particular emphasis on how automation itself can block some
forms of testing.</p>
</div>
</section>
<section id="features">
<h2>Features<a class="headerlink" href="#features" title="Permalink to this heading">¶</a></h2>
<ul class="simple">
<li><p><strong>Automated validation</strong> - designed for automated processes to create,
submit and process results of test jobs to validate the development
process.</p></li>
<li><p><strong>Parallel scheduling</strong> - multiple test jobs run at the same time
across multiple devices.</p></li>
<li><p><strong>MultiNode test jobs</strong> - test jobs can be run as a single group of
tests involving multiple devices.</p></li>
<li><p><strong>Hardware sharing</strong> - uncommon hardware is shared between disparate
groups to maximize usage</p></li>
<li><p><strong>Wide device coverage</strong> - a large number of types of device can be
supported with instances ranging from one to more than a hundred
devices available for test jobs.</p></li>
<li><p><strong>Data export for customisation</strong> - transform the data using custom
interfaces to make the validation output directly relevant to specific
teams.</p></li>
<li><p><strong>Privacy support</strong> - test jobs or types of device can be kept private
to selected groups, individuals or teams.</p></li>
<li><p><strong>Live result reporting</strong> - if a test job does fail, all results
up to the point of failure are retained.</p></li>
<li><p><strong>UNIX and Android test support</strong> - Test jobs can be run on systems
running various UNIX flavors or using the Android Debug Bridge to
interface with mobile devices.</p></li>
<li><p><strong>Complex network testing</strong> - reconfigurable networking across multiple
devices using multiple network interfaces.</p></li>
</ul>
</section>
<section id="architecture">
<h2>Architecture<a class="headerlink" href="#architecture" title="Permalink to this heading">¶</a></h2>
<img alt="_images/arch-overview.svg" src="_images/arch-overview.svg" /><p>A LAVA <code class="docutils literal notranslate"><span class="pre">instance</span></code> consists of two primary components - a server and a
<a class="reference internal" href="glossary.html#term-worker"><span class="xref std std-term">worker</span></a>. The simplest possible configuration is to run the master and
worker components on a single machine, but a larger instance can also be
configured to support multiple workers controlling a larger number of attached
devices.</p>
<section id="elements-of-the-master">
<h3>Elements of the Master<a class="headerlink" href="#elements-of-the-master" title="Permalink to this heading">¶</a></h3>
<ul class="simple">
<li><p><strong>Web interface</strong> - This is built using the Apache web server, the uWSGI
application server and the Django web framework. It also provides XML-RPC
access and the REST API.</p></li>
<li><p><strong>Database</strong> - This uses PostgreSQL locally on the master, with no external
access.</p></li>
<li><p><strong>Scheduler</strong> - This is the piece that causes jobs to be run - periodically
this will scan the database to check for queued test jobs and available test
devices, starting jobs when the needed resources become available.</p></li>
<li><p><strong>lava-server-gunicorn daemon</strong> - This communicates with the worker(s) using HTTP</p></li>
</ul>
</section>
<section id="elements-of-the-worker">
<h3>Elements of the Worker<a class="headerlink" href="#elements-of-the-worker" title="Permalink to this heading">¶</a></h3>
<ul class="simple">
<li><p><strong>lava-worker daemon</strong> - This receives control messages from the server.</p></li>
<li><p><strong>Dispatcher</strong> - This manages all the operations on the device under test,
according to the job submission and device parameters sent by the master.</p></li>
<li><p><strong>Device Under Test (DUT)</strong></p></li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Although the Dispatcher interacts directly with the <a class="reference internal" href="glossary.html#term-DUT"><span class="xref std std-term">DUT</span></a>, all
the device configuration is sent from the server.</p>
</div>
</section>
</section>
<section id="preparation">
<span id="overview-preparation"></span><h2>Preparation<a class="headerlink" href="#preparation" title="Permalink to this heading">¶</a></h2>
<p>LAVA has a steep learning curve and this does not tend to level off as your lab
grows. Even small labs involve additional hardware, infrastructure and
administrative tasks.</p>
<ol class="arabic simple">
<li><p>Do <strong>not</strong> rush into LAVA setup.</p></li>
<li><p><a class="reference internal" href="simple-admin.html#simple-admin-small"><span class="std std-ref">Start small</span></a>.</p></li>
<li><p>Think carefully about what you are trying to test. Avoid common pitfalls of
<a class="reference internal" href="simple-admin.html#simplistic-testing-problems"><span class="std std-ref">simplistic testing</span></a>.</p></li>
<li><p>Learn <a class="reference internal" href="simple-admin.html#admin-debug-information"><span class="std std-ref">how to debug LAVA</span></a> with a small lab
and <a class="reference internal" href="standard-test-jobs.html#using-gold-standard-files"><span class="std std-ref">use standard test jobs</span></a>.</p></li>
<li><p>Invest in <a class="reference internal" href="advanced-installation.html#infrastructure-requirements"><span class="std std-ref">additional hardware</span></a> - a
device on your desk is not a good candidate for automation.</p></li>
<li><p><a class="reference internal" href="first-job.html#submit-first-job"><span class="std std-ref">Test with emulated devices</span></a> before thinking about
the device on your priority list.</p>
<ul class="simple">
<li><p>Integrating a completely new <a class="reference internal" href="glossary.html#term-device-type"><span class="xref std std-term">device type</span></a> is the probably <strong>the most
complex thing to do in LAVA</strong>. It can take a few months of work for
devices which do not use currently supported methods or bootloaders.</p></li>
</ul>
</li>
<li><p>Start by adding <a class="reference internal" href="first-devices.html#first-devices"><span class="std std-ref">known devices</span></a>, including purchasing
some of the low-cost devices already supported by LAVA.</p></li>
<li><p><a class="reference internal" href="support.html#getting-support"><span class="std std-ref">Talk to us</span></a> before looking at device types not
currently supported on LAVA instances.</p></li>
</ol>
</section>
<section id="methods">
<h2>Methods<a class="headerlink" href="#methods" title="Permalink to this heading">¶</a></h2>
<section id="deployment-methods">
<h3>Deployment methods<a class="headerlink" href="#deployment-methods" title="Permalink to this heading">¶</a></h3>
<p>All test jobs involve a deployment step of some kind, even if that is just to
prepare the overlay used to copy the test scripts onto the device or to setup
the process of parsing the results when the test job starts.</p>
</section>
<section id="boot-methods">
<h3>Boot methods<a class="headerlink" href="#boot-methods" title="Permalink to this heading">¶</a></h3>
<p>Hardware devices need to be instructed how to boot, emulated devices need to
boot the emulator. For other devices, a <code class="docutils literal notranslate"><span class="pre">boot</span></code> can be simply establishing a
connection to the device.</p>
</section>
<section id="test-methods">
<h3>Test methods<a class="headerlink" href="#test-methods" title="Permalink to this heading">¶</a></h3>
<p>The principal test method in LAVA is the Lava Test Shell which requires a POSIX
type environment to be running on the booted device. Other test methods
available include executing tests using ADB.</p>
</section>
<section id="multiple-device-testing">
<h3>Multiple device testing<a class="headerlink" href="#multiple-device-testing" title="Permalink to this heading">¶</a></h3>
<p>Some test jobs need to boot up multiple devices in a single, coordinated,
group. For example, a server could be tested against multiple clients. LAVA
supports starting these sub jobs as a group as well as passing messages between
nodes via the dispatcher connection, without needing the devices to have a
working network stack.</p>
</section>
<section id="scheduling">
<span id="id6"></span><h3>Scheduling<a class="headerlink" href="#scheduling" title="Permalink to this heading">¶</a></h3>
<p>LAVA has advanced support for scheduling multiple jobs across multiple devices,
whether those jobs use one device or several. Scheduling is ordered using these
criteria, in this order:</p>
<ol class="arabic simple">
<li><p><a class="reference internal" href="glossary.html#term-health-check"><span class="xref std std-term">health checks</span></a></p></li>
<li><p><a class="reference internal" href="glossary.html#term-priority"><span class="xref std std-term">priority</span></a></p></li>
<li><p>submit time</p></li>
<li><p>multinode group - see also <a class="reference internal" href="multinode.html#multinode"><span class="std std-ref">MultiNode LAVA</span></a></p></li>
</ol>
<p>In addition, scheduling can be restricted to devices specified by the admin
using:</p>
<ul class="simple">
<li><p><a class="reference internal" href="glossary.html#term-device-tag"><span class="xref std std-term">device tags</span></a></p></li>
<li><p>user access limits - see <a class="reference internal" href="glossary.html#term-restricted-device"><span class="xref std std-term">restricted device</span></a> or
<a class="reference internal" href="glossary.html#term-hidden-device-type"><span class="xref std std-term">hidden device type</span></a>.</p></li>
</ul>
</section>
<section id="advanced-use-cases">
<h3>Advanced use cases<a class="headerlink" href="#advanced-use-cases" title="Permalink to this heading">¶</a></h3>
<p>Advanced use cases expand on this support to include:</p>
<ul class="simple">
<li><p>creating and deleting customized virtual networks, where suitable hardware
and software support exists.</p></li>
<li><p>extracting data from LAVA to manage job submission and result handling to
support developer-specific tasks like <a class="reference external" href="https://kernelci.org/">KernelCI</a>.</p></li>
</ul>
<div class="toctree-wrapper compound">
</div>
</section>
</section>
<section id="glossary">
<h2>Glossary<a class="headerlink" href="#glossary" title="Permalink to this heading">¶</a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary of terms</a></li>
</ul>
</div>
</section>
<section id="support">
<h2>Support<a class="headerlink" href="#support" title="Permalink to this heading">¶</a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="support.html">Getting support</a></li>
</ul>
</div>
</section>
<section id="full-documentation">
<h2>Full documentation<a class="headerlink" href="#full-documentation" title="Permalink to this heading">¶</a></h2>
<p>LAVA  comes with <a class="reference internal" href="contents.html#contents-top"><span class="std std-ref">comprehensive documentation</span></a>
about use and installation, including advice on how to manage a test
lab.</p>
</section>
</section>


    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
        &copy; Copyright 2010-2019, Linaro Limited.<br/>
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
    </p>
  </div>
</footer>
  </body>
</html>